home *** CD-ROM | disk | FTP | other *** search
/ Precision Software Appli…tions Silver Collection 1 / Precision Software Applications Silver Collection Volume One (PSM) (1993).iso / windows / games / wincapt.arj / DIBAPI.TXT < prev    next >
Text File  |  1992-06-24  |  33KB  |  840 lines
  1.  
  2.          DIB Screen Capture/Printing API Specification
  3.                 By Pat Schreiber and Mark Bader
  4.                  Version dated March 27, 1992
  5.  
  6. The following document contains descriptions of the functions
  7. defined in the DIBAPI dynamic-linked library.  This DLL
  8. demonstrates using the Windows Device-Independent Bitmap (DIB)
  9. functions to capture the screen, print bitmaps, convert between
  10. bitmap formats, and to display DIBs.
  11.  
  12. The DIBAPI DLL is a component of the WINCAP sample program,
  13. available in the Microsoft Software Library as WINCAP.ZIP.
  14. This sample program demonstrates using these APIs.
  15.  
  16. To use these APIs in your own program, first compile the
  17. DIBAPI.DLL using the DIBAPI.MAK make file.  Then, in your
  18. program, simply include the DIBAPI.H header file, and link with
  19. the DIBAPI.LIB import library (and make sure DIBAPI.DLL is in
  20. your path).
  21.  
  22. -Mark & Pat
  23.  
  24. ===============================================================
  25. BitmapToDIB
  26. Syntax    HDIB BitmapToDIB(hBitmap, hPal)
  27.           
  28.           This function creates a device-independent bitmap
  29.           (DIB) from a device-dependent bitmap using the
  30.           specified palette.  The DIB format is the same as the
  31.           hBitmap parameter.
  32.           
  33.           Parameter      Type/Description
  34.           hBitmap        HBITMAPSpecifies the handle to the
  35.                                 bitmap to convert.
  36.           
  37.           hPal           HPALETTE    Specifies the handle to
  38.                                 the palette associated with
  39.                                 the bitmap.
  40.           
  41. Return Value   The value returned identifies the device-
  42.           independent bitmap if the function is successful.
  43.           Otherwise, it is NULL.
  44.  
  45. Comments  The bitmap and palette remain intact after calling
  46.           this function. They should be deleted using the
  47.           Windows DeleteObject function once they are no longer
  48.           needed.
  49.  
  50.  
  51. ChangeBitmapFormat
  52. Syntax    HDIB ChangeBitmapFormat(hBitmap, wBitCount,
  53.                     dwCompression, hPal)
  54.           
  55.           This function converts a bitmap to a DIB of the
  56.           specified bits per pixel and compression format using
  57.           the specified palette.
  58.           
  59.           Parameter      Type/Description
  60.           hBitmap        HBITMAPSpecifies the handle to the
  61.                                 bitmap.
  62.           
  63.           wBitCount      WORD   Specifies the desired bits per
  64.                                 pixel.
  65.           
  66.           dwCompression  DWORD  Specifies the desired
  67.                                 compression format. Must be
  68.                                 one of the following:
  69.                                 BI_RGB, BI_RLE4, or BI_RLE8.
  70.           
  71.           hPal           HPALETTE    Specifies the handle to
  72.                                 the palette associated with
  73.                                 the bitmap.
  74.           
  75. Return Value   The value returned identifies the device-
  76.           dependent bitmap if the function is successful.
  77.           Otherwise, it is NULL.
  78.  
  79. Comments  The bitmap and palette remain intact after calling
  80.           this function. They should be deleted using the
  81.           Windows DeleteObject function once they are no longer
  82.           needed.
  83.  
  84.  
  85. ChangeDIBFormat
  86. Syntax    HDIB ChangeDIBFormat(hDIB, wBitCount, dwCompression)
  87.           
  88.           This function changes the bits per pixel and
  89.           compression format of the given DIB to those
  90.           specified by the wBitCount and dwCompression.
  91.           
  92.           Parameter      Type/Description
  93.           hBitmap        HBITMAPSpecifies the handle to the
  94.                                 bitmap.
  95.           
  96.           wBitCount      WORD   Specifies the desired bits per
  97.                                 pixel.
  98.           
  99.           dwCompression  DWORD  Specifies the desired
  100.                                 compression format. Must be
  101.                                 one of the following:
  102.                                 BI_RGB, BI_RLE4, or BI_RLE8.
  103.           
  104.           hPal           HPALETTE    Specifies the handle to
  105.                                 the palette associated with
  106.                                 the bitmap.
  107.           
  108. Return Value   The value returned identifies the device-
  109.           dependent bitmap if the function is successful.
  110.           Otherwise, it is NULL.
  111.  
  112. Comments  The original DIB is left intact after calling this
  113.           function. It should be deleted using
  114.           DestroyDIBDestroyDIB once it is no longer needed.
  115.  
  116.  
  117. CopyScreenToBitmap
  118. Syntax    HBITMAP CopyScreenToBitmap(lpRect)
  119.           
  120.           This function copies the specified part of the screen
  121.           to a device-dependent bitmap.
  122.           
  123.           Parameter      Type/Description
  124.           lpRect         LPRECT Pointer to a RECT data
  125.                                 structure that contains the
  126.                                 rectangle to be copied.
  127.           
  128. Return Value   The value returned identifies the deice-
  129.           dependent bitmap if the function is successful.
  130.           Otherwise, it is NULL.
  131.  
  132. Comments  The bitmap should be deleted using the Windows
  133.           DeleteObject function once it is no longer needed.
  134.  
  135.  
  136. CopyScreenToDIB
  137. Syntax    HDIB CopyScreenToDIB(lpRect)
  138.           
  139.           This function copies the specified part of the screen
  140.           to a device-independent bitmap.
  141.           
  142.           Parameter      Type/Description
  143.           lpRect         LPRECT Pointer to a RECT data
  144.                                 structure that contains the
  145.                                 rectangle to be copied.
  146.           
  147. Return Value   The value returned identifies the device-
  148.           independent bitmap if the function is successful.
  149.           Otherwise, it is NULL.
  150.  
  151. Comments  The DIB should be deleted using the
  152.           DestroyDIBDestroyDIB function once it is no longer
  153.           needed.
  154.  
  155.  
  156. CopyWindowToBitmap
  157. Syntax    HBITMAP CopyWindowToBitmap(hWnd, fPrintArea)
  158.           
  159.           This function copies the specified part of  the
  160.           window to a device-dependent bitmap.
  161.           
  162.           Parameter      Type/Description
  163.           hWnd           HWND   Specifies the window.
  164.           
  165.           fPrintArea     WORD   Specifies the window area(s) to
  166.                                 copy into the device-
  167.                                 independent bitmap.
  168.           
  169.           The fPrintArea parameter must be one of the
  170.                                 following:
  171.           
  172.           Value          Meaning
  173.           PW_WINDOW      Copy the entire window.
  174.           
  175.           PW_CLIENT      Copy only the client area of the given
  176.                                 window.
  177.           
  178. Return Value   The value returned identifies the device-
  179.           dependent bitmap if the function is successful.
  180.           Otherwise, it is NULL.
  181.  
  182. Comments  The bitmap should be deleted using the Windows
  183.           DeleteObject function once it is no longer needed.
  184.  
  185.  
  186. CopyWindowToDIB
  187. Syntax    HDIB CopyWindowToDIB(hWnd, fPrintArea)
  188.           
  189.           This function copies the specified part of the window
  190.           to a device-independent bitmap.
  191.           
  192.           Parameter      Type/Description
  193.           hWnd           HWND   Specifies the window.
  194.           
  195.           fPrintArea     WORD   Specifies the window area(s) to
  196.                                 copy into the device-
  197.                                 independent bitmap.
  198.           
  199.           The fPrintArea parameter must be one of the
  200.                                 following:
  201.           
  202.           Value          Meaning
  203.           PW_WINDOW      Copy the entire window.
  204.           
  205.           PW_CLIENT      Copy only the client area of the given
  206.                                 window.
  207.           
  208.           
  209. Return Value   The value returned identifies the device-
  210.           independent bitmap if the function is successful.
  211.           Otherwise, it is NULL.
  212.  
  213. Comments  The DIB should be deleted using the
  214.           DestroyDIBDestroyDIB function once it is no longer
  215.           needed.
  216.  
  217.  
  218. CreateDIBPalette
  219. Syntax    HPALETTE CreateDIBPalette(hDIB)
  220.           
  221.           This function creates a logical palette from the
  222.           color table of the specified DIB.
  223.           
  224.           Parameter      Type/Description
  225.           hDIB           HDIB   Specifies the handle to the
  226.                                 DIB.
  227.           
  228. Return Value   The value returned identifies the logical
  229.           palette corresponding to the DIB's color table.
  230.           Otherwise, it is NULL.
  231.  
  232. Comments  The palette should be deleted using the Windows
  233.           DeleteObject function once it is no longer needed.
  234.  
  235.  
  236. CreateDIB
  237. Syntax    HDIB CreateDIB(dwWidth, dwHeight, wBitCount)
  238.           
  239.           This function allocates memory for and initializes a
  240.           new DIB by filling in the BITMAPINFOHEADER,
  241.           allocating memory for the color table, and allocating
  242.           memory for the bitmap bits. The color table and
  243.           bitmap bits are all set to zeros.  As with all HDIBs,
  244.           the header, color table, and bits are all in one
  245.           contiguous memory block. This function is similar to
  246.           the Windows CreateBitmap function.
  247.           
  248.           Parameter      Type/Description
  249.           dwWidth        DWORD  Specifies the width of the new
  250.                                 DIB in pixels.
  251.           
  252.           dwHeight       DWORD  Specifies the height of the new
  253.                                 DIB in pixels.
  254.           
  255.           wBitCount      WORD   Specifies the bits per pixel of
  256.                                 the new DIB. This must be one
  257.                                 of the following: 1, 4, 8, or
  258.                                 24.
  259.           
  260. Return Value   The value returned identifies the new DIB.
  261.           Otherwise, it is NULL.
  262.  
  263. Comments  The DIB should be deleted using the
  264.           DestroyDIBDestroyDIB function once it is no longer
  265.           needed.
  266.  
  267.  
  268. DestroyDIB
  269. Syntax    WORD DestroyDIB(hDib)
  270.           
  271.           This function destroys the specified DIB, deleting
  272.           any memory associated with the DIB.  The handle to
  273.           the DIB is invalid after calling this function.
  274.           
  275.           Parameter      Type/Description
  276.           hDib           HDIB   Specifies the handle to the DIB
  277.                                 to destroy.
  278.           
  279. Return Value   The value returned is zero for success.
  280.  
  281.  
  282. DIBError
  283. Syntax    void DIBError(ErrNo)
  284.           
  285.           This function displays a MessageBox with an error
  286.           message corresponding to the specified error number.
  287.           
  288.           Parameter      Type/Description
  289.           ErrNo          int    Specifies the error message to
  290.                                 display.
  291.           
  292.           The error message must be one of the following:
  293.           
  294.           Value          Meaning
  295.           ERR_NOT_DIB  Tried to load a non-DIB file.
  296.           
  297.           ERR_MEMORY   Not enough memory.
  298.           
  299.           ERR_READ     Error reading a file.
  300.           
  301.           ERR_LOCK     Error on a GlobalLock.
  302.           
  303.           ERR_OPEN     Error opening a file.
  304.           
  305.           ERR_CREATEPAL       Error creating a palette.
  306.           
  307.           ERR_GETDC    Error getting a DC.
  308.           
  309.           ERR_CREATEDDB       Error creating a bitmap.
  310.           
  311.           ERR_STRETCHBLT      StretchBlt failed.
  312.           
  313.           ERR_STRETCHDIBITS   StretchDIBits failed.
  314.           
  315.           ERR_SETDIBITSTODEVICE    SetDIBitsToDevice failed.
  316.           
  317.           ERR_STARTDOC Error calling StartDoc.
  318.           
  319.           ERR_NOGDIMODULE     GDI module was not in memory.
  320.                                 
  321.           ERR_SETABORTPROC    Error calling SetAbortProc.
  322.           
  323.           ERR_STARTPAGE       Error calling StartPage.
  324.           
  325.           ERR_NEWFRAME Error calling NEWFRAME escape.
  326.           
  327.           ERR_ENDPAGE  Error calling EndPage.
  328.           
  329.           ERR_ENDDOC   Error calling EndDoc.
  330.           
  331.           ERR_SETDIBITS       Error calling SetDIBits.
  332.           
  333.           ERR_FILENOTFOUND    Error opening file in
  334.                                 LoadDIBLoadDIB.
  335.           
  336.           ERR_INVALIDHANDLE   Invalid handle.
  337.           
  338.           ERR_DIBFUNCTION     Error on call to DIB function.
  339.           
  340. Return Value   None.
  341.  
  342.  
  343. DIBHeight
  344. Syntax    DWORD DIBHeight(lpDIB)
  345.           
  346.           This function gets the height of the specified DIB.
  347.           
  348.           Parameter      Type/Description
  349.           lpDIB          LPSTR  Specifies the DIB.
  350.           
  351. Return Value   The value returned specifies the height of the
  352.           DIB.
  353.  
  354. Comments  This function requires a pointer to a DIB rather than
  355.           an HDIB.  In order to use this function with an HDIB,
  356.           you must first call the Windows GlobalLock function
  357.           on the HDIB, and pass the resulting pointer to this
  358.           function.
  359.  
  360.  
  361. DIBNumColors
  362. Syntax    WORD DIBNumColors(lpDIB)
  363.           
  364.           This function calculates the number of colors in
  365.           color table of the specified DIB specification.
  366.           
  367.           Parameter      Type/Description
  368.           lpDIB          LPSTR  Pointer to a DIB specification.
  369.           
  370. Return Value   The value returned specifies the number of
  371.           colors in the color table.
  372.  
  373. Comments  This function requires a pointer to a DIB rather than
  374.           an HDIB.  In order to use this function with an HDIB,
  375.           you must first call the Windows GlobalLock function
  376.           on the HDIB, and pass the resulting pointer to this
  377.           function.
  378.  
  379.  
  380. DIBToBitmap
  381. Syntax    HBITMAP DIBToBitmap(hDIB, hPal)
  382.           
  383.           This function creates a device-dependent bitmap from
  384.           the specified DIB and palette.
  385.           
  386.           Parameter      Type/Description
  387.           hDIB           HDIB   Specifies the DIB.
  388.           
  389.           hPal           HPALETTE    Specifies the handle to
  390.                                 the palette.
  391.           
  392. Return Value   The value returned identifies the device-
  393.           dependent bitmap. Otherwise, it is NULL.
  394.  
  395. Comments  The original DIB is left intact after calling this
  396.           function. It should be deleted using
  397.           DestroyDIBDestroyDIB once it is no longer needed.
  398.  
  399.           The bitmap returned from this function is always a
  400.           bitmap compatible with the screen (e.g. same
  401.           bits/pixel and color planes) rather than a bitmap
  402.           with the same attributes as the DIB.  This behavior
  403.           is by design, and occurs because this function calls
  404.           the Windows CreateDIBitmap function to do its work,
  405.           and CreateDIBitmap always creates a bitmap compatible
  406.           with the hDC parameter passed in (because it in turn
  407.           calls the Windows CreateCompatibleBitmap function).
  408.           
  409.           So for instance, if your DIB is a monochrome DIB and
  410.           you call this function, you will not get back a
  411.           monochrome HBITMAP -- you will get an HBITMAP
  412.           compatible with the screen DC, but with only 2 colors
  413.           used in the bitmap.  If your application requires a
  414.           monochrome HBITMAP returned for a monochrome DIB, use
  415.           the Windows function SetDIBits instead.
  416.  
  417.  
  418. DIBWidth
  419. Syntax    DWORD DIBWidth(lpDIB)
  420.           
  421.           This function gets the width of the specified DIB.
  422.           
  423.           Parameter      Type/Description
  424.           lpDIB          LPSTR  Specifies the DIB.
  425.           
  426. Return Value   The value returned specifies the width of the
  427.           DIB.
  428.  
  429. Comments  This function requires a pointer to a DIB rather than
  430.           an HDIB.  In order to use this function with an HDIB,
  431.           you must first call the Windows GlobalLock function
  432.           on the HDIB, and pass the resulting pointer to this
  433.           function.
  434.  
  435.  
  436. FindDIBBits
  437. Syntax    LPSTR FindDIBBits(lpDIB)
  438.           
  439.           This function finds and returns a pointer to the
  440.           specified DIB's bits.
  441.           
  442.           Parameter      Type/Description
  443.           lpDIB          LPSTR  Pointer to the DIB
  444.                                 specification.
  445.           
  446. Return Value   The value returned is a pointer to the DIB's
  447.           bits.
  448.  
  449. Comments  This function requires a pointer to a DIB rather than
  450.           an HDIB.  In order to use this function with an HDIB,
  451.           you must first call the Windows GlobalLock function
  452.           on the HDIB, and pass the resulting pointer to this
  453.           function.
  454.  
  455.  
  456. GetSystemPalette
  457. Syntax    HPALETTE GetSystemPalette(void)
  458.           
  459.           This function returns a logical palette that
  460.           represents the current system palette.
  461.           
  462. Return Value   The value returned identifies the logical
  463.           palette representing the current system palette.
  464.  
  465. Comments  The palette should be deleted using the Windows
  466.           DeleteObject function once it is no longer needed.
  467.  
  468.  
  469. LoadDIB
  470. Syntax    HDIB LoadDIB(lpFileName)
  471.           
  472.           This function loads a DIB from the specified file,
  473.           allocates memory for the DIB, and returns a handle to
  474.           the DIB.
  475.           
  476.           Parameter      Type/Description
  477.           lpFileName     LPSTR  Specifies the complete path
  478.                                 name of the DOS filename of
  479.                                 the DIB to load.  This
  480.                                 function will load files with
  481.                                 any extension, but the
  482.                                 convention is to name DIB
  483.                                 files with a .BMP extension.
  484.           
  485. Return Value   The value returned identifies the deice-
  486.           dependent bitmap if the function is successful.
  487.           Otherwise, it is NULL.
  488.  
  489. Comments  This function is similar to the Windows LoadBitmap
  490.           function, but there are a few major differences:
  491.  
  492.           1. The filename passed into this function is the name
  493.           of a Disk-based file rather than a resource in the
  494.           executable.  You can specify a full path name for the
  495.           filename if required.
  496.           
  497.           2. This function will preserve the bitmap's color
  498.           format when it loads the DIB.  For instance, if you
  499.           load a 256-color DIB with this function, the DIB is
  500.           stored in memory as a 256-color DIB.  The Windows
  501.           LoadBitmap function always reduces a DIBs color
  502.           format to the reserved system colors (e.g. for a 256-
  503.           color bitmap on a 256-color display, the LoadBitmap
  504.           function will color-reduce the bitmap to 20 colors).
  505.           
  506.           3. This function returns a HDIB rather than an
  507.           HBITMAP.
  508.           
  509.           The DIB should be deleted using the
  510.           DestroyDIBDestroyDIB function once it is no longer
  511.           needed.
  512.  
  513.  
  514. PaintBitmap
  515. Syntax    BOOL PaintBitmap(hDC, lpDCRect, hDDB, lpDDBRect,
  516.                     hPalette)
  517.           
  518.           This function draws the specified bitmap in the given
  519.           DC. The bitmap is output to the DC at the coordinates
  520.           given by lpDCRect. The area of the bitmap to be
  521.           output is given by the lpDDBRect parameter.
  522.           
  523.           Parameter      Type/Description
  524.           hDC            HDC    Specifies the output DC. The
  525.                                 bitmap specified by hDDB must
  526.                                 be compatible with this DC.
  527.           
  528.           lpDCRect       LPRECT Specifies the destination
  529.                                 coordinates of the bitmap
  530.                                 being drawn.
  531.           
  532.           hDDB           HBITMAPSpecifies the bitmap.
  533.           
  534.           lpDDBRect      LPRECT Specifies the area of the
  535.                                 bitmap to be drawn.
  536.           
  537.           hPalette       HPALETTE    Specifies the palette to
  538.                                 be used in drawing the bitmap.
  539.           
  540. Return Value   The value returned is non-zero if successful.
  541.           Otherwise, it is zero.
  542.  
  543. Comments  Note that the palette is selected and realized as a
  544.           background palette. If a foreground palette is
  545.           needed, it must be selected as foreground and
  546.           realized before calling this function.
  547.  
  548.  
  549. PaintDIB
  550. Syntax    BOOL PaintDIB(hDC, lpDCRect, hDIB, lpDIBRect, hPal)
  551.           
  552.           This function draws the specified DIB in the given
  553.           DC. The DIB is output to the DC at the coordinates
  554.           given by lpDCRect. The area of the DIB to be output
  555.           is given by the lpDIBRect parameter.
  556.           
  557.           Parameter      Type/Description
  558.           hDC            HDC    Specifies the output DC. The
  559.                                 bitmap specified by hDDB must
  560.                                 be compatible with this DC.
  561.           
  562.           lpDCRect       LPRECT Specifies the destination
  563.                                 coordinates of the bitmap
  564.                                 being drawn.
  565.           
  566.           hDIB           HDIB   Specifies the DIB.
  567.           
  568.           lpDIBRect      LPRECT Specifies the area of the DIB
  569.                                 to be drawn.
  570.           
  571.           hPal           HPALETTE    Specifies the palette to
  572.                                 be associated with the DIB.
  573.           
  574. Return Value   The value returned is non-zero if successful.
  575.           Otherwise, it is zero.
  576.  
  577. Comments  Note that the palette is selected and realized as a
  578.           background palette. If a foreground palette is
  579.           needed, it must be selected as foreground and
  580.           realized before calling this function.
  581.  
  582.  
  583. PaletteSize
  584. Syntax    WORD PaletteSize(lpDIB)
  585.           
  586.           This function gets the size required to store the
  587.           specified DIB's palette.
  588.           
  589.           Parameter      Type/Description
  590.           lpDIB          LPSTR  Pointer to a DIB specification.
  591.           
  592. Return Value   The value returned specifies the size of the
  593.           DIB's color palette.
  594.  
  595. Comments  This function requires a pointer to a DIB rather than
  596.           an HDIB.  In order to use this function with an HDIB,
  597.           you must first call the Windows GlobalLock function
  598.           on the HDIB, and pass the resulting pointer to this
  599.           function.
  600.  
  601.  
  602. PalEntriesOnDevice
  603. Syntax    int PalEntriesOnDevice(hDC)
  604.           
  605.           This function gets the number of palette entries on a
  606.           specified device.
  607.           
  608.           Parameter      Type/Description
  609.           hDC            HDC    Specifies the device.
  610.           
  611. Return Value   The value returned specifies the number of
  612.           palette entries.
  613.  
  614.  
  615. PrintDIB
  616. Syntax    WORD PrintDIB(hDib, fPrintOpt, wXScale, wYScale,
  617.                     szJobName)
  618.  
  619.           This function prints the specified DIB.
  620.  
  621.           Parameter      Type/Description
  622.           hDib           HDIB   Specifies the handle to a DIB
  623.                                 which is to be printed
  624.           
  625.           fPrintOpt      WORD   Specifies the printing option.
  626.           
  627.           wXScale        WORD   Specifies the x-axis scaling
  628.                                 factor for the printed window.
  629.                                 The x and y scaling factors
  630.                                 are only used if the PW_SCALE
  631.                                 option is selected for the
  632.                                 fPrintOpt parameter.
  633.           
  634.           wYScale        WORD   Specifies the y-axis scaling
  635.                                 factor.
  636.           
  637.           szJobName      LPSTR  Specifies the name of the print
  638.                                 job.  This string is used in
  639.                                 the job name sent to the print
  640.                                 spooler, as well as in the
  641.                                 print dialog box.
  642.           
  643.           The fPrintOpt parameter must be set to one of the
  644.           following:
  645.           
  646.           Value             Meaning
  647.           PW_BESTFIT        Fits the printed screen on the page
  648.                             in as large of a area as possible
  649.                             while still retaining the correct
  650.                             screen aspect ratio.  The wXScale
  651.                             and wYScale parameters are not
  652.                             used if this option is selected.
  653.                             This is the default value.
  654.           
  655.           PW_STRETCHTOPAGE  Stretches the printed screen to
  656.                             fill up the entire printed page.
  657.                             The wXScale and wYScale parameters
  658.                             are not used if this option is
  659.                             selected.
  660.           
  661.           PW_SCALE          Scales the printed screen by the
  662.                             integer scaling factors specified
  663.                             in the wXScale and wYScale
  664.                             parameters.   If the scaling is
  665.                             set too large, the screen may
  666.                             extend off the printed page and
  667.                             will be clipped.
  668.  
  669. Return Value   0 if successful, or one of:  ERR_INVALIDHANDLE,
  670.           ERR_LOCK, ERR_SETABORTPROC, ERR_STARTDOC,
  671.           ERR_NEWFRAME, ERR_ENDDOC, ERR_GETDC,
  672.           ERR_STRETCHDIBITS.  These constants are defined in
  673.           dibapi.h.
  674.  
  675.  
  676. PrintScreen
  677. Syntax    WORD PrintScreen(rRegion, fPrintOpt, wXScale,
  678.                     wYScale, szJobName)
  679.           
  680.           This function prints the specified area of the screen
  681.           on the default printer.
  682.           
  683.           Parameter      Type/Description
  684.           rRegion        LPRECT Specifies the region of the
  685.                                 screen (in screen coordinates)
  686.                                 to be printed.  To print the
  687.                                 entire screen, set this RECT
  688.                                 to encompass the entire
  689.                                 screen.
  690.           
  691.           fPrintOpt      WORD   Species the printing options.
  692.           
  693.           wXScale        WORD   Specifies the x-axis scaling
  694.                                 factor for the printed window.
  695.                                 The x and y scaling factors
  696.                                 are only used if the PW_SCALE
  697.                                 option below is selected.
  698.           
  699.           wYScale        WORD   Specifies the y-axis scaling
  700.                                 factor.
  701.           
  702.           szJobName      LPSTR  Specifies the name of the print
  703.                                 job.  This string is used in
  704.                                 the job name sent to the print
  705.                                 spooler, as well as in the
  706.                                 print dialog box.
  707.           
  708.           The fPrintOpt parameter must be set to one of the
  709.           following:
  710.           
  711.           Value             Meaning
  712.           PW_BESTFIT        Fits the printed screen on the page
  713.                             in as large of a area as possible
  714.                             while still retaining the correct
  715.                             screen aspect ratio.  The wXScale
  716.                             and wYScale parameters are not
  717.                             used if this option is selected.
  718.                             This is the default value.
  719.           
  720.           PW_STRETCHTOPAGE  Stretches the printed screen to
  721.                             fill up the entire printed page.
  722.                             The wXScale and wYScale parameters
  723.                             are not used if this option is
  724.                             selected.
  725.           
  726.           PW_SCALE          Scales the printed screen by the
  727.                             integer scaling factors specified
  728.                             in the wXScale and wYScale
  729.                             parameters.   If the scaling is
  730.                             set too large, the screen may
  731.                             extend off the printed page and
  732.                             will be clipped.
  733.           
  734. Return Value   0 if successful, or one of: ERR_DIBFUNCTION,
  735.           ERR_INVALIDHANDLE, ERR_LOCK, ERR_SETABORTPROC,
  736.           ERR_STARTDOC, ERR_NEWFRAME, ERR_ENDDOC, ERR_GETDC,
  737.           ERR_STRETCHDIBITS.  These constants are defined in
  738.           dibapi.h.
  739.  
  740.  
  741. PrintWindow
  742. Syntax    WORD PrintWindow(hWnd, fPrintArea, fPrintOpt,
  743.                     wXScale, wYScale, szJobName)
  744.           
  745.           This function prints an entire window or its client
  746.           area on the current default printer.  Banding is used
  747.           if the printer driver supports it.
  748.           
  749.           Parameter      Type/Description
  750.           hWnd           HWND   Specifies the window to be
  751.                                 printed.
  752.           
  753.           fPrintArea     WORD   Specifies the area(s) of the
  754.                                 window to be printed.  See
  755.                                 below for a listing of the
  756.                                 possible values for this
  757.                                 parameter.
  758.           
  759.           fPrintOpt      WORD   Species the printing options.
  760.                                 See below for a listing of the
  761.                                 possible values for this
  762.                                 parameter.
  763.           
  764.           wXScale        WORD   Specifies the x-axis scaling
  765.                                 factor for the printed window.
  766.                                 The x and y scaling factors
  767.                                 are only used if the PW_SCALE
  768.                                 option below is selected.
  769.           
  770.           wYScale        WORD   Specifies the y-axis scaling
  771.                                 factor.
  772.           
  773.           szJobName      LPSTR  Specifies the name of the print
  774.                                 job.  This string is used in
  775.                                 the job name sent to the print
  776.                                 spooler, as well as in the
  777.                                 print dialog box.
  778.           
  779.           The fPrintArea parameter must be set to one of the
  780.           following:
  781.           
  782.           Value             Meaning
  783.           PW_WINDOW         Print the entire window.
  784.           
  785.           PW_CLIENT         Print the client area of the
  786.                             window.
  787.           
  788.           The fPrintOpt parameter must be set to one of the
  789.           following:
  790.           
  791.           Value             Meaning
  792.           PW_BESTFIT        Fits the printed screen on the page
  793.                             in as large of a area as possible
  794.                             while still retaining the correct
  795.                             screen aspect ratio.  The wXScale
  796.                             and wYScale parameters are not
  797.                             used if this option is selected.
  798.                             This is the default value.
  799.           
  800.           PW_STRETCHTOPAGE  Stretches the printed screen to
  801.                             fill up the entire printed page.
  802.                             The wXScale and wYScale parameters
  803.                             are not used if this option is
  804.                             selected.
  805.           
  806.           PW_SCALE          Scales the printed screen by the
  807.                             integer scaling factors specified
  808.                             in the wXScale and wYScale
  809.                             parameters.   If the scaling is
  810.                             set too large, the screen may
  811.                             extend off the printed page and
  812.                             will be clipped.
  813.           
  814. Return Value   0 if successful, or one of: ERR_DIBFUNCTION,
  815.           ERR_INVALIDHANDLE, ERR_LOCK, ERR_SETABORTPROC,
  816.           ERR_STARTDOC, ERR_NEWFRAME, ERR_ENDDOC, ERR_GETDC,
  817.           ERR_STRETCHDIBITS.  These constants are defined in
  818.           errors.h.
  819.  
  820.  
  821. SaveDIB
  822. Syntax    WORD SaveDIB(hDib, lpFileName)
  823.  
  824.           This function saves the specified DIB to a disk file
  825.           in Windows 3 DIB format.  Although the convention for
  826.           naming DIB files is to use a .BMP extension, the
  827.           entire file name must be specified.
  828.  
  829.           Parameter      Type/Description
  830.           hDib           HDIB   Specifies the handle to a DIB
  831.                                 which is to be saved.
  832.  
  833.           lpFileName     LPSTR  Specifies the complete path
  834.                                 name of the DOS filename under
  835.                                 which this DIB is to be saved.
  836.  
  837. Return Value   The value returned is zero for success or an
  838.           error code of one of the following:
  839.           ERR_INVALIDHANDLE, ERR_OPEN, or ERR_LOCK.
  840.